Migration Guide: Hotel Search v11 to SearchComplete

Introduction

This migration guide assists developers in transitioning from the Hotel JSON API v11 to the new SearchComplete API.

Important: This is Not a Re-platform

A re-platform typically implies moving the same product onto new infrastructure without changing how it works. SearchComplete is fundamentally different - this is a re-architecture, not just new plumbing.

Here's why:

1. Simpler Workflows, Not Just New Infrastructure

• v11 forces users to chain together multiple endpoints to get the full picture (Search > Availability > Rules)

• SearchComplete consolidates this into a single unified endpoint, so users get MORE done in fewer calls

• The workflow itself has been redesigned for simplicity and efficiency

2. Better Data and Responses

• v11 had a limited data set spread across multiple responses

• SearchComplete delivers a MUCH more robust set of response data in a single call

• Enhanced filtering capabilities (room filters, rate filters) not available in v11

• Complete rate rules and policies included immediately

3. New Technology Under the Hood

• SearchComplete is backed by intelligent caching with header-based controls

• Cache controls speed up responses and give consumers control over cache access

• v11 had no caching capabilities, making it slower with no user control

• Significantly improved response times through architectural optimization

4. Built for the Future, Not Just for Today

• SearchComplete introduces content scoring and structured property metadata

• v11 was built to mirror legacy systems; SearchComplete is built to grow

• Modern architecture enables faster innovation and feature delivery

• Designed to support evolving traveler needs and market requirements

Bottom Line: The move from v11 to SearchComplete is NOT a "lift and shift." It's a comprehensive redesign and upgrade that reduces complexity for developers, delivers faster and richer responses for travelers, and positions Travelport for faster innovation going forward. Calling it a "re-platform" undersells what SearchComplete delivers - we've fundamentally changed the workflows, the performance, and the developer experience.

What You'll Find in This Guide

This guide provides comprehensive details on migrating from v11 to SearchComplete, including:

• Detailed workflow comparisons showing the architectural differences

• Step-by-step migration instructions for each v11 endpoint

• Request and response structure mappings

• Code examples demonstrating the simplified integration

• Performance and caching improvements

• Best practices for leveraging new capabilities

Overview of Hotel JSON API v11 Workflow

As a quick refresher, v11 requires three sequential API calls to complete a hotel search:

The Problem: You need all three responses to make a booking decision, which means managing state, correlating identifiers, and handling three potential failure points.

Overview of SearchComplete API

What Changes: One endpoint replaces all three v11 calls. You send your search criteria once and receive properties with availability, rates, AND rules in a single response.

What You Send:

• stayDetails: Check-in/out dates and guest counts (replaces v11 CheckInDate, CheckOutDate, RoomStayCandidate)

• propertyFilter: Location and property criteria (replaces v11 SearchBy)

• roomFilter: NEW - Filter by room attributes (smoking, bed type, accessible, etc.)

• rateFilter: NEW - Filter by rate characteristics (refundable, breakfast included, etc.)

What You Get Back:

• Complete property information (same as v11 search response)

• Available rates with full pricing (replaces v11 availability call)

• Rate rules including cancellation and payment policies (replaces v11 rules call)

• Room details and amenities

• All in one unified JSON structure

Critical Difference: You no longer need to manage CatalogOfferingIdentifiers or make sequential calls. Everything needed for booking is in the first response.

Key Differences Between v11 and SearchComplete

Summary Comparison

Detailed Migration Steps

This section maps your v11 implementation to SearchComplete. If you're familiar with v11, use this as your primary reference for converting your code.

Quick Reference: Parameter Mapping

Request Structure Changes

Key Change: Parameters are now organized into logical groups instead of a flat structure.

1. Date and Guest Parameters > stayDetails

v11 had CheckInDate, CheckOutDate, and RoomStayCandidate as separate fields. SearchComplete groups these into stayDetails:

//v11

{
 "CheckInDate": "2025-03-15",
 "CheckOutDate": "2025-03-17",
 "RoomStayCandidate": [
  {
   "GuestCount": {
    "AdultCount": 2,
    "ChildCount": 1,
    "ChildAge": [
     5
    ]
   }
  }
 ]
}

//SearchComplete

{
 "stayDetails": {
  "checkInDateLocal": "2025-03-15",
  "checkOutDateLocal": "2025-03-17",
  "guests": {
   "numberOfAdults": 2,
   "numberOfChildren": 1,
   "childAges": [
    5
   ]
  }
 }
}

2. Location Parameters > propertyFilter.location

v11 SearchBy becomes propertyFilter.location with a simpler structure:

//v11

{
 "SearchBy": {
  "@type": "SearchByLocation",
  "Address": {
   "CityName": "San Francisco",
   "CountryCode": "US"
  }
 }
}

//SearchComplete - no @type discriminators

{
 "propertyFilter": {
  "location": {
   "city": "San Francisco",
   "countryCode": "US"
  }
 }
}

3. NEW: Advanced Filtering (Not Available in v11)

roomFilter - Filter results by room characteristics:

• nonSmoking: Only return non-smoking rooms

• balcony: Only return rooms with balconies

• accessible: Only return accessible rooms

• bedConfiguration: Specify bed type preferences (king, queen, twin)

rateFilter - Filter results by rate characteristics:

• rateFlags: Filter by refundable, breakfast included, etc.

• publicRateBlacklist: Exclude specific rate types

Response Structure Changes

Critical Change: No More Sequential Calls

In v11, you had to extract property identifiers from the search response, then make separate availability and rules calls. SearchComplete eliminates this entirely.

What You Used to Do (v11)

• Search Response: Extract PropertyIdentifier from each property

• Availability Call: Send PropertyIdentifier[] to /availability/catalogofferingshospitality

• Availability Response: Extract CatalogOfferingIdentifier from each rate

• Rules Call: Send CatalogOfferingIdentifier to /rules/offershospitality/buildfromcatalogoffering

• Rules Response: Get cancellation policies, deposit requirements, etc.

What You Do Now (SearchComplete)

• Search Request: Send your search criteria

• Search Response: Get everything - properties, rates, AND rules in one response

• Response Structure: Where to Find Things

The SearchComplete response is structured as:

• response.hotelsResponse.hotels[] = Array of hotel objects Each hotel object contains:

• propertyInfo: Property details (name, address, rating, etc.)

• location: Coordinates and full address

• amenities: Property amenities

• images: Property images

• rates[]: Array of available rates < THIS IS NEW

• Each rate object contains (replaces v11 availability + rules):

• rateInfo: Rate description and offer details

• pricing: Complete breakdown (base, taxes, fees, total)

• roomType: Room description and amenities

• mealPlan: Meal inclusions

• rateRules: < THIS REPLACES THE RULES CALL

  • cancelPolicy: Cancellation deadlines and penalties

  • depositPolicy: Deposit requirements

  • guaranteePolicy: Guarantee requirements

• bedConfiguration: Bed types available

• paymentOptions: Accepted payment methods

Request Structure Comparison

v11 Search Request Example

"PropertiesQuerySearch": { "@type": "PropertiesQuerySearch", 
  "CheckInDate": "2025-03-15",
  "CheckOutDate": "2025-03-17", 
  "RequestedCurrency": "USD", "SearchBy": {
  "@type": "SearchByLocation", "Address": {
    "CityName": "San Francisco", 
    "CountryCode": "US"
}
},
"RoomStayCandidate": [
{
"GuestCount": { "AdultCount": 2
}
}
],
"returnOnlyAvailablePropertiesInd": true
}
}
}

SearchComplete Request Example

{
 "stayDetails": {
  "checkInDateLocal": "2025-03-15",
  "checkOutDateLocal": "2025-03-17",
  "guests": {
   "numberOfAdults": 2,
   "numberOfChildren": 0
  }
 },
 "propertyFilter": {
  "location": {
   "city": "San Francisco",
   "countryCode": "US"
  },
  "returnOnlyAvailableProperties": true,
  "returnRateSummaryInfo": true,
  "imageSize": "LARGE",
  "returnAllImageURLs": true
 },
 "roomFilter": {
  "nonSmoking": true,
  "bedConfiguration": {
   "preferredBedTypes": [
    "KING"
   ]
  }
 },
 "requestedCurrency": "USD",
 "returnCompleteNightlyRateBreakdown": true
}

Key Differences in Request Structure:

• Organized Parameters: SearchComplete groups related parameters into logical objects (stayDetails, propertyFilter, roomFilter)

• Enhanced Filtering: SearchComplete provides roomFilter and rateFilter for more precise results

• Cleaner Structure: No "@type" discriminators needed in SearchComplete

• Better Naming: More intuitive parameter names (checkInDateLocal vs CheckInDate)

• Single Request: One request replaces three separate v11 calls

Response Structure Comparison

v11 Response Structure

Three Separate Responses Required:

1. Search Response - Contains property information only:

• Property basic details (name, address, coordinates)

• Property amenities

• Images

• Star rating

• NO rate information

• NO availability information

2. Availability Response - Contains rate information:

• Available room types

• Rate identifiers

• Pricing (base rate, taxes, fees)

• Meal plans

• NO rate rules or policies

3. Rules Response - Contains policy information:

• Cancellation policies

• Deposit requirements

• Guarantee requirements

• Check-in/out policies

• Rate restrictionss

SearchComplete Response Structure

Single Comprehensive Response - Contains everything:

• traceId: Request tracking identifier

• transactionId: Transaction identifier

• pagination: Pagination details for large result sets

• hotelsResponse: Main response object containing hotels[], an array of hotel objects, each containing:

  • propertyInfo: Complete property details

  • location: Address and coordinates

  • amenities: Property amenities

  • images: Property images

  • rates[]: Array of available rates, each containing:

    • 1xrateInfo: Rate description and details

    • pricing: Complete pricing breakdown

    • roomType: Room configuration and details

    • mealPlan: Meal inclusions

    • rateRules: Complete policies (cancellation, deposit, guarantee)

    • bedConfiguration: Bed types

    • paymentOptions: Accepted payment methods

Key Advantages:

• All Information Available Immediately: No need to correlate data across three responses

• Simplified Data Model: Clear, hierarchical structure

• Better Performance: Single request/response cycle

• Easier Error Handling: One point of failure instead of three

• Reduced Complexity: No need to manage state across multiple calls

Code Examples

Before and After: Real Implementation Comparison v11: Three Separate Calls

SearchComplete: Single Call

Key Takeaway: You eliminate identifier management, state tracking across calls, and multiple error handling points. Everything you need is in one response structure.

General Changes and Considerations

Authentication

Both v11 and SearchComplete APIs use OAuth 2.0 Bearer tokens for authentication. No changes are required to your authentication implementation.

Performance and Caching

SearchComplete introduces significant performance improvements over v11:

Intelligent Caching Architecture:

• Built-in cache layer with header-based controls

• Cache-Control headers allow consumers to specify caching behavior

• ETag support for efficient cache validation

• Significantly faster response times for cached results

• Reduced load on backend systems

• v11 had NO caching capabilities—every request hit the backend

API Call Efficiency:

• SearchComplete reduces API calls by 66% (3 calls > 1 call)

• Lower cumulative latency due to consolidated request/response

• More efficient rate limit usage (1 call vs. 3 calls per search)

• Reduced bandwidth consumption overall

• Better caching opportunities for client applications

Error Handling

SearchComplete uses standard HTTP status codes and returns errors in a consistent JSON format.

{
 "errors": [
  {
   "code": "INVALID_REQUEST",
   "message": "Check-in date must be in the future",
   "field": "stayDetails.checkInDateLocal"
  }
 ]
}

Benefits:

• Single point of error handling instead of three

• More descriptive error messages

• Field-level error attribution

• Warnings array for non-fatal issues

Pagination

SearchComplete implements intelligent pagination for large result sets:

• Initial request returns first page of results

• Response includes pagination object with nextIdentifier

• More efficient than v11 offset-based pagination

• Enhanced Data and Metadata

• SearchComplete provides significantly richer data compared to v11: Complete Data in Initial Response:

• Full rate rules included (no separate rules call needed)

• Complete pricing breakdown with taxes and fees

• Room amenities and descriptions

• Payment options and requirements

• Meal plan details

• Special offers and promotions

• Nightly rate breakdowns (when requested)

New Capabilities Not Available in v11:

• Content Scoring: Intelligent scoring algorithms help rank and prioritize results

• Structured Property Metadata: Enhanced property information with standardized formats

• Advanced Filtering: Room-level and rate-level filters for precise results

• Enhanced Image Support: More control over image sizes and quantity

• Rate Category Support: Better handling of corporate, government, and special rates

• Amenity Categories: Structured amenity data for easier filtering and display

• Future-Ready Architecture:

• Unlike v11, which was built to mirror legacy systems, SearchComplete is designed with a modern, extensible architecture that supports rapid innovation. New features and capabilities can be added more quickly without requiring major structural changes.

Common Migration Gotchas

Watch Out For These Differences:

No More @type Discriminators

{
 "PropertiesQuerySearch": {
  "@type": "PropertiesQuerySearch",
  "SearchBy": {
   "@type": "SearchByLocation"
  }
 }
}

SearchComplete

{
"stayDetails": { ... }, 
"propertyFilter": {
"location": { ... }
}
}

Guest Counts Are Structured Differently

v11 used RoomStayCandidate with nested GuestCount. SearchComplete flattens this:

v11

"RoomStayCandidate": [
{ "GuestCount": { "AdultCount": 2, "ChildCount": 1, "ChildAge": [5] } }
]

v12

"guests": {
"numberOfAdults": 2,
"numberOfChildren": 1,
"childAges": [5]
}

Rate Data Is Directly in the Search Response

Don't look for a separate availability response. Rates are in hotels[].rates[] immediately.

No CatalogOfferingIdentifier to Track

v11 required you to save CatalogOfferingIdentifier to make the rules call. SearchComplete includes rules in the rate object, so you don't need to track identifiers between calls.

Error Handling Changes

With v11, you had to handle failures at three different points (search, availability, rules). SearchComplete has a single point of failure, but you should check the errors and warnings arrays in the response for any issues.

Caching Headers Matter Now

SearchComplete supports caching with Cache-Control and ETag headers. If you want fresh data, use "Cache-Control: no-cache" in your request. Otherwise, you may get cached results (which is often fine and much faster).

Migration Timeline Recommendations

• Phase 1: Parallel Testing - Run both v11 and SearchComplete in test environment

• Phase 2: Validate Responses - Ensure SearchComplete provides equivalent data

• Phase 3: Update Integration - Modify code to use SearchComplete endpoints

• Phase 4: User Acceptance Testing - Test with real booking scenarios

• Phase 5: Production Cutover - Switch production traffic to SearchComplete

• Phase 6: Monitor and Optimize - Track performance and errors post-migration

Conclusion

SearchComplete: A Re-Architecture, Not a Re-Platform

The SearchComplete API represents a fundamental re-architecture of hotel search and booking capabilities, not simply a re-platform of existing functionality. This is a comprehensive redesign that transforms the developer experience and delivers superior results for travelers.

What Makes This a Re-Architecture:

• Workflow Redesign: Consolidated 3-step process into a single, intelligent endpoint

• Enhanced Data Model: Richer, more complete data with structured metadata

• Modern Infrastructure: Built-in caching and performance optimization

• Future-Ready Design: Extensible architecture supporting rapid innovation

• Improved Developer Experience: Simpler integration with more powerful capabilities

Technical Benefits:

• Reduced API calls from 3 to 1 (66% reduction)

• Lower latency with caching support (v11 had none)

• Simplified integration code and workflow management

• Better error handling and debugging

• More efficient rate limit usage

• Header-based cache controls for consumer flexibility

Business Benefits:

• Faster time-to-market for new features

• Reduced infrastructure costs through efficiency

• Improved user experience with faster searches

• Better rate transparency for customers

• Enhanced filtering for more relevant results

• Content scoring for better property ranking

• Foundation for future innovation and growth

The Bottom Line:

This migration is not about moving to new infrastructure with the same capabilities. SearchComplete fundamentally changes how hotel search works—reducing complexity for developers, delivering faster and richer responses for travelers, and establishing a modern foundation for continuous innovation.

We strongly recommend migrating to SearchComplete to take advantage of these architectural improvements and position your application for future enhancements.

For additional support:

• Contact your Travelport account manager

• Review the API documentation

• Submit support tickets through the developer portal

Document Feedback

We value your feedback on this documentation. If you have suggestions for improvements, find errors, or need clarification on any topic, please contact:

• Your Travelport Account Manager

• Travelport Support team

• Developer Portal feedback form

For urgent API issues or production support, contact Travelport support immediately.